Make global GDK libgtk_only functions more private

The current way of exposing GDK API that should be considered internal
to GTK+ is to append a 'libgtk_only' suffix to the function name; this
is not really safe.

GLib has been using a slightly different approach: a private table of
function pointers, and a macro that allows accessing the desired symbol
inside that vtable.

We can copy the approach, and deprecate the 'libgtk_only' symbols in
lieu of outright removal.

https://bugzilla.gnome.org/show_bug.cgi?id=739781

diff --git a/gdk/Makefile.am b/gdk/Makefile.am
index 618dec533ad8b761c556bda73a984beba66b3e88..ac459b780e64cfcb5af2a6f5cc6a22fa296c7bff 100644 (file)
--- a/gdk/Makefile.am
+++ b/gdk/Makefile.am
@@ -99,6 +99,7 @@ gdk_h_sources =                                       \
        $(deprecated_h_sources)
 
 gdk_private_headers =                          \
+       gdk-private.h                           \
        gdkapplaunchcontextprivate.h            \
        gdkcursorprivate.h                      \
        gdkdevicemanagerprivate.h               \
@@ -121,6 +122,7 @@ deprecated_c_sources =                              \
 
 gdk_c_sources =                                \
        $(deprecated_c_sources)                 \
+       gdk-private.c                           \
        gdk.c                                   \
        gdkapplaunchcontext.c                   \
        gdkcairo.c                              \

diff --git a/gdk/gdk-private.c b/gdk/gdk-private.c
new file mode 100644 (file)
index 0000000..0dbd035
--- /dev/null
+++ b/gdk/gdk-private.c
@@ -0,0 +1,15 @@
+#include "config.h"
+#include "gdk-private.h"
+
+GdkPrivateVTable *
+gdk__private__ (void)
+{
+  static GdkPrivateVTable table = {
+    gdk_device_grab_info,
+    gdk_display_open_default,
+    gdk_add_option_entries,
+    gdk_pre_parse,
+  };
+
+  return &table;
+}

diff --git a/gdk/gdk-private.h b/gdk/gdk-private.h
new file mode 100644 (file)
index 0000000..7061647
--- /dev/null
+++ b/gdk/gdk-private.h
@@ -0,0 +1,35 @@
+#ifndef __GDK__PRIVATE_H__
+#define __GDK__PRIVATE_H__
+
+#include <gdk/gdk.h>
+
+#define GDK_PRIVATE_CALL(symbol)        (gdk__private__ ()->symbol)
+
+GdkDisplay *    gdk_display_open_default        (void);
+
+gboolean        gdk_device_grab_info            (GdkDisplay  *display,
+                                                 GdkDevice   *device,
+                                                 GdkWindow  **grab_window,
+                                                 gboolean    *owner_events);
+
+void            gdk_add_option_entries          (GOptionGroup *group);
+
+void            gdk_pre_parse                   (void);
+
+typedef struct {
+  /* add all private functions here, initialize them in gdk-private.c */
+  gboolean (* gdk_device_grab_info) (GdkDisplay  *display,
+                                     GdkDevice   *device,
+                                     GdkWindow  **grab_window,
+                                     gboolean    *owner_events);
+
+  GdkDisplay *(* gdk_display_open_default) (void);
+
+  void (* gdk_add_option_entries) (GOptionGroup *group);
+  void (* gdk_pre_parse) (void);
+} GdkPrivateVTable;
+
+GDK_AVAILABLE_IN_ALL
+GdkPrivateVTable *      gdk__private__  (void);
+
+#endif /* __GDK__PRIVATE_H__ */

diff --git a/gdk/gdk.c b/gdk/gdk.c
index 951a01ccbd2806971102321662d30a60451aeb75..068ecc4f4cf535d510d1ad3b171fa7e1fff6476b 100644 (file)
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -30,6 +30,8 @@
 #include "gdkinternals.h"
 #include "gdkintl.h"
 
+#include "gdk-private.h"
+
 #ifndef HAVE_XCONVERTCASE
 #include "gdkkeysyms.h"
 #endif
@@ -239,21 +241,30 @@ static const GOptionEntry gdk_args[] = {
   { NULL }
 };
 
+void
+gdk_add_option_entries (GOptionGroup *group)
+{
+  g_option_group_add_entries (group, gdk_args);
+}
+
 /**
  * gdk_add_option_entries_libgtk_only:
  * @group: An option group.
  *
  * Appends gdk option entries to the passed in option group. This is
  * not public API and must not be used by applications.
+ *
+ * Deprecated: 3.16: This symbol was never meant to be used outside
+ *   of GTK+
  */
 void
 gdk_add_option_entries_libgtk_only (GOptionGroup *group)
 {
-  g_option_group_add_entries (group, gdk_args);
+  gdk_add_option_entries (group);
 }
 
 void
-gdk_pre_parse_libgtk_only (void)
+gdk_pre_parse (void)
 {
   const char *rendering_mode;
   const gchar *gl_string;
@@ -302,6 +313,20 @@ gdk_pre_parse_libgtk_only (void)
     }
 }
 
+/**
+ * gdk_pre_parse_libgtk_only:
+ *
+ * Prepare for parsing command line arguments for GDK. This is not
+ * public API and should not be used in application code.
+ *
+ * Deprecated: 3.16: This symbol was never meant to be used outside
+ *   of GTK+
+ */
+void
+gdk_pre_parse_libgtk_only (void)
+{
+  gdk_pre_parse ();
+}
   
 /**
  * gdk_parse_args:
@@ -330,7 +355,7 @@ gdk_parse_args (int    *argc,
   if (gdk_initialized)
     return;
 
-  gdk_pre_parse_libgtk_only ();
+  gdk_pre_parse ();
 
   option_context = g_option_context_new (NULL);
   g_option_context_set_ignore_unknown_options (option_context, TRUE);
@@ -389,8 +414,8 @@ gdk_get_display_arg_name (void)
    return _gdk_display_arg_name;
 }
 
-/**
- * gdk_display_open_default_libgtk_only:
+/*< private >
+ * gdk_display_open_default:
  *
  * Opens the default display specified by command line arguments or
  * environment variables, sets it as the default display, and returns
@@ -400,9 +425,9 @@ gdk_get_display_arg_name (void)
  *
  * Returns: (nullable) (transfer none): the default display, if it
  *   could be opened, otherwise %NULL.
- **/
+ */
 GdkDisplay *
-gdk_display_open_default_libgtk_only (void)
+gdk_display_open_default (void)
 {
   GdkDisplay *display;
 
@@ -417,6 +442,27 @@ gdk_display_open_default_libgtk_only (void)
   return display;
 }
 
+/**
+ * gdk_display_open_default_libgtk_only:
+ *
+ * Opens the default display specified by command line arguments or
+ * environment variables, sets it as the default display, and returns
+ * it. gdk_parse_args() must have been called first. If the default
+ * display has previously been set, simply returns that. An internal
+ * function that should not be used by applications.
+ *
+ * Returns: (nullable) (transfer none): the default display, if it
+ *   could be opened, otherwise %NULL.
+ *
+ * Deprecated: 3.16: This symbol was never meant to be used outside
+ *   of GTK+
+ */
+GdkDisplay *
+gdk_display_open_default_libgtk_only (void)
+{
+  return gdk_display_open_default ();
+}
+
 /**
  * gdk_init_check:
  * @argc: (inout): the number of command line arguments.
@@ -439,7 +485,7 @@ gdk_init_check (int    *argc,
 {
   gdk_parse_args (argc, argv);
 
-  return gdk_display_open_default_libgtk_only () != NULL;
+  return gdk_display_open_default () != NULL;
 }
 
 

diff --git a/gdk/gdkdevice.h b/gdk/gdkdevice.h
index 23b3551d099649c9ea9e93d794021f24bbedc030..7e1094e9645624889aba2dbc1d743a3af9adf016 100644 (file)
--- a/gdk/gdkdevice.h
+++ b/gdk/gdkdevice.h
@@ -265,7 +265,7 @@ void          gdk_device_warp        (GdkDevice        *device,
                                       gint              x,
                                       gint              y);
 
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_16
 gboolean gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
                                            GdkDevice   *device,
                                            GdkWindow  **grab_window,

diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index d48491b611193f19cd82c4b0ee042edddc616618..7354a63c1795855b999918331b2c21737b433507 100644 (file)
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -24,6 +24,8 @@
 #include "gdkdisplay.h"
 #include "gdkdisplayprivate.h"
 
+#include "gdk-private.h"
+
 #include "gdkdeviceprivate.h"
 #include "gdkdisplaymanagerprivate.h"
 #include "gdkevents.h"
@@ -1293,8 +1295,8 @@ _gdk_display_pointer_info_foreach (GdkDisplay                   *display,
     }
 }
 
-/**
- * gdk_device_grab_info_libgtk_only:
+/*< private >
+ * gdk_device_grab_info:
  * @display: the display for which to get the grab information
  * @device: device to get the grab information from
  * @grab_window: (out) (transfer none): location to store current grab window
@@ -1307,12 +1309,12 @@ _gdk_display_pointer_info_foreach (GdkDisplay                   *display,
  *
  * Returns: %TRUE if this application currently has the
  *  keyboard grabbed.
- **/
+ */
 gboolean
-gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
-                                  GdkDevice   *device,
-                                  GdkWindow  **grab_window,
-                                  gboolean    *owner_events)
+gdk_device_grab_info (GdkDisplay  *display,
+                      GdkDevice   *device,
+                      GdkWindow  **grab_window,
+                      gboolean    *owner_events)
 {
   GdkDeviceGrabInfo *info;
 
@@ -1334,6 +1336,33 @@ gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
     return FALSE;
 }
 
+/**
+ * gdk_device_grab_info_libgtk_only:
+ * @display: the display for which to get the grab information
+ * @device: device to get the grab information from
+ * @grab_window: (out) (transfer none): location to store current grab window
+ * @owner_events: (out): location to store boolean indicating whether
+ *   the @owner_events flag to gdk_keyboard_grab() or
+ *   gdk_pointer_grab() was %TRUE.
+ *
+ * Determines information about the current keyboard grab.
+ * This is not public API and must not be used by applications.
+ *
+ * Returns: %TRUE if this application currently has the
+ *  keyboard grabbed.
+ *
+ * Deprecated: 3.16: The symbol was never meant to be used outside
+ *   of GTK+
+ */
+gboolean
+gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
+                                  GdkDevice   *device,
+                                  GdkWindow  **grab_window,
+                                  gboolean    *owner_events)
+{
+  return gdk_device_grab_info (display, device, grab_window, owner_events);
+}
+
 /**
  * gdk_display_pointer_is_grabbed:
  * @display: a #GdkDisplay

diff --git a/gdk/gdkdisplay.h b/gdk/gdkdisplay.h
index e82c533348e25b993c547e4fcd712d766f64aa75..a76af35bed0f634114a459a043e104f9802ac4e2 100644 (file)
--- a/gdk/gdkdisplay.h
+++ b/gdk/gdkdisplay.h
@@ -123,7 +123,7 @@ void             gdk_display_warp_pointer          (GdkDisplay             *disp
                                                     gint                   y);
 #endif /* GDK_MULTIDEVICE_SAFE */
 
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_16
 GdkDisplay *gdk_display_open_default_libgtk_only (void);
 
 GDK_AVAILABLE_IN_ALL

diff --git a/gdk/gdkmain.h b/gdk/gdkmain.h
index c574f34471a446d4ed865a6b4b3b556fb8717d40..09e087382b9ffd8d08c3f495de7bf9a98f401da7 100644 (file)
--- a/gdk/gdkmain.h
+++ b/gdk/gdkmain.h
@@ -49,9 +49,9 @@ void                  gdk_init                            (gint           *argc,
 GDK_AVAILABLE_IN_ALL
 gboolean              gdk_init_check                      (gint           *argc,
                                                            gchar        ***argv);
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_16
 void                  gdk_add_option_entries_libgtk_only  (GOptionGroup   *group);
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_16
 void                  gdk_pre_parse_libgtk_only           (void);
 
 GDK_AVAILABLE_IN_ALL

diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index e19691c0c573b76cdfc57861945c4617d3a4cc99..88e326051b668a5eaeaf78b254f1d2b437a0bd20 100644 (file)
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -91,6 +91,7 @@
 #include "config.h"
 
 #include "gdk/gdk.h"
+#include "gdk/gdk-private.h"
 
 #include <locale.h>
 
@@ -642,7 +643,7 @@ do_pre_parse_initialization (int    *argc,
   if (_gtk_module_has_mixed_deps (NULL))
     g_error ("GTK+ 2.x symbols detected. Using GTK+ 2.x and GTK+ 3 in the same process is not supported");
 
-  gdk_pre_parse_libgtk_only ();
+  GDK_PRIVATE_CALL (gdk_pre_parse) ();
   gdk_event_handler_set ((GdkEventFunc)gtk_main_do_event, NULL, NULL);
 
 #ifdef G_ENABLE_DEBUG
@@ -755,7 +756,7 @@ post_parse_hook (GOptionContext *context,
   
   if (info->open_default_display)
     {
-      if (gdk_display_open_default_libgtk_only () == NULL)
+      if (GDK_PRIVATE_CALL (gdk_display_open_default) () == NULL)
         {
           const char *display_name = gdk_get_display_arg_name ();
           g_set_error (error,
@@ -830,7 +831,7 @@ gtk_get_option_group (gboolean open_default_display)
   group = g_option_group_new ("gtk", _("GTK+ Options"), _("Show GTK+ Options"), info, g_free);
   g_option_group_set_parse_hooks (group, pre_parse_hook, post_parse_hook);
 
-  gdk_add_option_entries_libgtk_only (group);
+  GDK_PRIVATE_CALL (gdk_add_option_entries) (group);
   g_option_group_add_entries (group, gtk_args);
   g_option_group_set_translation_domain (group, GETTEXT_PACKAGE);
   
@@ -879,7 +880,7 @@ gtk_init_with_args (gint                 *argc,
   gboolean retval;
 
   if (gtk_initialized)
-    return gdk_display_open_default_libgtk_only () != NULL;
+    return GDK_PRIVATE_CALL (gdk_display_open_default) () != NULL;
 
   gettext_initialization ();
 
@@ -985,7 +986,7 @@ gtk_init_check (int    *argc,
   if (!gtk_parse_args (argc, argv))
     return FALSE;
 
-  ret = gdk_display_open_default_libgtk_only () != NULL;
+  ret = GDK_PRIVATE_CALL (gdk_display_open_default) () != NULL;
 
   if (debug_flags & GTK_DEBUG_INTERACTIVE)
     gtk_window_set_interactive_debugging (TRUE);
@@ -1338,12 +1339,6 @@ gtk_main_iteration_do (gboolean blocking)
     return TRUE;
 }
 
-/* private libgtk to libgdk interfaces */
-gboolean gdk_device_grab_info_libgtk_only (GdkDisplay  *display,
-                                           GdkDevice   *device,
-                                           GdkWindow  **grab_window,
-                                           gboolean    *owner_events);
-
 static void
 rewrite_events_translate (GdkWindow *old_window,
                           GdkWindow *new_window,
@@ -1446,7 +1441,7 @@ rewrite_event_for_grabs (GdkEvent *event)
       display = gdk_window_get_display (event->any.window);
       device = gdk_event_get_device (event);
 
-      if (!gdk_device_grab_info_libgtk_only (display, device, &grab_window, &owner_events) ||
+      if (!GDK_PRIVATE_CALL (gdk_device_grab_info) (display, device, &grab_window, &owner_events) ||
           !owner_events)
         return NULL;
       break;